/*
 * Copyright the original author or authors.
 * 
 * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.mozilla.org/MPL/MPL-1.1.html
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.kairos.utils.monitor
{
	import com.bourre.structures.Range;
	import com.kairos.engine.RTEvent;
	
	/**
	 * A <code>MonitorField</code> object represent a value which can be displayed
	 * in the <code>Monitor</code> object.
	 * 
	 * <p>Monitors fields can be labels, curve in the graph or both according to
	 * <code>isCurve()</code> and <code>isLabel()</code> returned value.</p>
	 * 
	 * @author  Cédric Néhémie
	 * @see		Monitor
	 */
	public interface MonitorField
	{		
		/**
		 * Returns the current value of the field formatted as a <code>String</code>.
		 * 
		 * <p>If the value have a specific unit, the formatted string
		 * will include it.</p>
		 * 
		 * @return <code>String</code> of the formatted value.
		 */
		function getFormattedValue () : String;
		
		/**
		 * Returns the color that the <code>Monitor</code> will use to create
		 * the field label and the field curve.
		 * 
		 * <p>Colors are described with ARGB hexadecimal value such
		 * <code>0xaarrggbb</code>.</p>
		 * 
		 * @return 	<code>Number</code> color of the field.
		 */
		function getColor() : Number;
		
		/**
		 * Returns the name of the current field which the <code>Monitor</code>
		 * will use as label for the field.
		 * 
		 * <p>As in general we used to display the smallest monitor as possible, 
		 * try to set a small and explicit label. The monitor will allways adjust
		 * the size of the monitor on the bitmap rather than on the labels so
		 * textfields will crop the text if it's longer than the allowed size.</p>
		 * 
		 * @return <code>String</code> name of the field
		 */
		function getName () : String;
		
		/**
		 * Returns the range between the last value and the current value
		 * of the field in the display bitmap coordinates.
		 * 
		 * <p>The range contained values in pixels according to the
		 * graph's bitmap height passed to this object when added
		 * to the <code>Monitor</code>. For example, for a monitor's
		 * bitmap with a height of 100, display range from 50 to 150,
		 * value of 100 and last value of 75 the method have to
		 * return a range from 75 to 50. The example below show a basic
		 * implementation of the <code>getDifference</code> method.</p>
		 * 
		 * <listing>public function getDifference () : Range
		 * {
		 * 	return new Range ( _getDisplayValue( _nLastValue ), _getDisplayValue( _nValue ) );
		 * }
		 * 
		 * protected function _getDisplayValue ( value : Number ) : Number
		 * {
		 * 	return _nBitmapHeight - Math.floor( ( ( value - _oDisplayRange.min ) / _oDisplayRange.max ) * _nBitmapHeight );
		 * }
		 * </listing>
		 * 
		 * <p>In that example the conversion of a value in the display
		 * bitmap coordinates is performed by a protected method called
		 * <code>_getDisplayValue</code>.</p>
		 * 
		 * @return <code>Range</code> of value variations.
		 */
		function getDifference() : Range;
		
		/**
		 * Defines the color of the current field.
		 * 
		 * <p>The color have to be defined before its add to the <code>Monitor</code>
		 * otherwise the modification isn't considered.</p>
		 * 
		 * <p>Colors are described with ARGB hexadecimal value such
		 * <code>0xaarrggbb</code>.</p>
		 * 
		 * @param	col	<code>Number</code> color for the field.
		 */
		function setColor( col : Number ) : void;
		
		/**
		 * Defines the height of the display area. That value is set
		 * by the <code>Monitor</code> when the object is added to it.
		 * 
		 * <p>That value have to be used to compute the <code>getDifference</code>
		 * return value.</p>
		 * 
		 * @param	n	<code>Number</code> of the graph's bitmap height.
		 */
		function setDisplayHeight( n:Number ) : void;
		
		/**
		 * Defines the display values range for the field. All values out
		 * of that range isn't displayed in the graph.</p>
		 * 
		 * <p>That range have to be used to compute the <code>getDifference</code>
		 * return value.</p>
		 * 
		 * @param	r	<code>Range</code> of displayed values.
		 */
		function setDisplayRange ( r : Range ) : void;
		
		/**
		 * Called by the <code>Monitor</code> on each frame of the
		 * animation.
		 * 
		 * <p>In that method the object set the last value and register
		 * its current value from its source. The example below show how
		 * to simply implements the <code>registerValue</code> method.</p>
		 * 
		 * <listing>public function registerValue( e : RTEvent ) : void
		 * {
		 * 	_nLastValue = _nValue;
		 * 	_nValue = theTargetObject.theTargetProperty;
		 * }
		 * </listing>
		 * 
		 * <p>Its important to also register the last value in the same time,
		 * if ommitted the monitor cannot draw the line, it can only draw
		 * a single pixel for the sole value.</p>
		 * 
		 * @param 	e	The RTEvent dispatched by the <code>RTBeacon</code>.
		 */
		function registerValue ( e : RTEvent ) : void;
		
		/**
		 * Returns <code>true</code> if the field can be displayed as curve
		 * in the graph, <code>false</code> otherwise.
		 * 
		 * @return <code>true</code> if the field is a curve in the graph.
		 */
		function isCurve () : Boolean;
		
		/**
		 * Returns <code>true</code> if the field can be displayed as label
		 * in the monitor, <code>false</code> otherwise.
		 * 
		 * @return <code>true</code> if the field have a label in the monitor.
		 */
		function isLabel () : Boolean;
		
		/**
		 * Defines if the field curves is drawn on the screen or not.
		 * 
		 * @param b	<code>true</code> to draw the curve, <code>false</code> either.
		 */
		function setEnabled( b : Boolean ) : void;
		
		/**
		 * Returns <code>true</code> if the curve is drawn on the graph, <code>false</code> either.
		 * 
		 * @return <code>true</code> if the curve is drawn on the graph, <code>false</code> either.
		 */
		function isEnabled () : Boolean;
	}
}